% cGENIE README document

% Andy Ridgwell, August 2014
%
% ---------------------------------------------------------------------------------------------------------------------------------
% ---------------------------------------------------------------------------------------------------------------------------------

\documentclass[10pt,twoside]{article}
\usepackage[paper=a4paper,portrait=true,margin=2.5cm,ignorehead,footnotesep=1cm]{geometry}
\usepackage{graphicx}
\usepackage{hyperref}
\usepackage{paralist}
\usepackage{caption}
\usepackage{float}

\linespread{1.1}
\setlength{\pltopsep}{2.5pt}
\setlength{\plparsep}{2.5pt}
\setlength{\partopsep}{2.5pt}
\setlength{\parskip}{2.5pt}

\title{READ-ME for cGENIE: 'muffin' pre-release version}
\author{Andy Ridgwell}
\date{\today}

\begin{document}


%=================================================================================================================================
%=== BEGIN DOCUMENT ==============================================================================================================
%=================================================================================================================================

\maketitle


%=================================================================================================================================
%=== CONTENTS ====================================================================================================================
%=================================================================================================================================

%\tableofcontents


%---------------------------------------------------------------------------------------------------------------------------------
%--- cGENIE READ-ME --------------------------------------------------------------------------------------------------------------
%---------------------------------------------------------------------------------------------------------------------------------


\subsection{Whats new in the 'muffin' branch of cGENIE?}


\textit{c}GENIE is a cutdown and simplified, carbon cycle centric version of the 'GENIE' Earth system model. 'muffin' is the current development branch of \textit{c}GENIE.

There are a few relatively minor changes in the way that the muffin branch of cGENIE is configured and run compared to previous versions of 'GENIE' and the standard cGENIE branch.

\begin{compactenum}

\item Firstly: some of the (rarely if ever used, or simply not working and/or redundant) science modules such as the IGCM atmospheric GCM model have been deleted. It is hence no longer necessary (nor even possible) to do the \texttt{make assumedgood} test as part of the model installation procedure.

\item In installing: no additional directories need be created.
(The \texttt{\~{}/cgenie\_output} directory is automatically created if you have run e.g. `\texttt{make testbiogem}' during model installation.)

\item The recommended way to run cGENIE is via \texttt{runmuffin.sh}\footnote{This script is configured for running on a specific computing cluster, and may require adapting to a different computing environment.}\footnote{Note the file \texttt{runmuffin.sh} \textbf{MUST} have executable permissions (you can add executable permissions by typing the command: \texttt{chmod u+x runcgenie.sh}).} -- a script that carries out the basic configuration tasks and packages up the results for you. It also diagnoses and sets the appropriate time-stepping depending on the ocean circulation module resolution specified in the \textit{base-config}. \texttt{runmuffin.sh} is held under SVN and resides in the directory \texttt{\~{}/cgenie.muffin/genie-main}, from where experiments are run.
 
\item The complete command line looks like:
\vspace{-5pt}\small\begin{verbatim}
./runmuffin.sh cgenie.eb_go_gs_ac_bg.worjh2.ANTH / EXAMPLE.worjh2.Caoetal2009.SPIN 10000
\end{verbatim}\normalsize\vspace{-5pt}
  
Note that no path is given for the \textit{user-configs} other than `/' because cGENIE is expecting \texttt{\~{}/cgenie.muffin/genie-userconfigs} by default.

If you use a subdirectory of \texttt{\~{}/cgenie.muffin/genie-userconfigs} then you would specify the subdirectory name in place of `/', e.g.: \texttt{LABS}.

\item As part of the initialization -- misspelt or plain non-existing parameter names are now automatically checked-for (and model execution will stop and let you know).

\item Previously, the forcing directory was set in the \textit{user-config} file by the namelist parameter:
\\ \texttt{bg\_par\_fordir\_name}.
\\ Now the forcing directory is set to \texttt{\~{}/cgenie.muffin/genie-forcings} as default and the namelist parameter: \texttt{bg\_par\_fordir\_name} needs not be set (to anything different).
Instead, which forcing is used is set by the namelist parameter: \texttt{bg\_par\_forcing\_name}, e.g.:
\vspace{-5pt}\begin{verbatim}
bg_par_forcing_name='worjh2_preindustrial_FeMahowald2006'
\end{verbatim}\vspace{-0pt}

\item The same \texttt{runmuffin.sh} script can be used to submit jobs to the cluster. For example:
\vspace{-5pt}\small\begin{verbatim}
qsub -j y -o cgenie_log -V -S /bin/bash
runmuffin.sh cgenie.eb_go_gs_ac_bg.worjh2.ANTH / EXAMPLE.worjh2.Caoetal2009.SPIN 10000
\end{verbatim}\normalsize\vspace{-5pt}
  
\item The \textit{base-config} files have been somewhat rationalized.
\\Muffin-friendly \textit{base-config} files have the naming format starting '\texttt{cgenie.}' in
\\ \texttt{\~{}/cgenie.muffin/genie-main/configs}

\item It is no longer necessary (ever!) to manually request a \texttt{make cleanall} -- \textit{c}GENIE now keeps track of the lase \textit{base-config} used and will automatically \texttt{make cleanall} if you start using a different one.

\item Output is now split up -- the \texttt{runmuffin.sh} script saves the archived experiment \texttt{.tar.gz} file in the directory\texttt{~/cgenie\_archive}, which is created automatically if it does not exist. The job submission (above) specifies that the submission log is saved to\texttt{~/cgenie\_log} -- again, automatically created if is does not already exist.

\end{compactenum}


%=================================================================================================================================
%=== END DOCUMENT ================================================================================================================
%=================================================================================================================================

\end{document}
